ParcelLabel API

(2 reviews)

Create label(s) - EX NZ - US Tradelane

How to generate international parcel labels for parcels being sent from New Zealand to US via the Courier Select_US

This service needs to be enabled by NZ Post before a merchant can use the service. Please contact your NZ Post account manager to activate the service you require.

Service Description

Service Name	Service Code	Destination Country	Service Specific Rules
Intl Courier Select United States	ICOUSUS	US	• Additional insurance is available for this service • It only supports single parcel

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels

A unique consignment_id is returned once the details of the request are stored in the labeling database.

Request Parameters

In the following table, we have provided which fields are required in the label request for the Courier Select_US service.

A JSON sample for service ICOUSUS is provided below.

Field Name	Type (Length Limit)	Description	Required?
carrier	string	Carrier of the parcel. Value must be PARCELPOST	Yes - ParcelPost
format	string	Format of the label. Value must be PDF or PNG. Default Value is PDF.	No
notification_endpoint	string(2048)	Merchants Webhook URL to receive notification when the label has been generated.	No
sender_reference_1	string(35)	Sender's reference for the consignment. Will be printed on the label.	No
sender_reference_2	string(35)	Sender's reference. Will not be printed on the label.	No
paper_dimensions	object	An object containing the paper size upon which to print the label. See Paper Dimension Object Parameters section.	No
paper_dimensions.width_cm	number	Width the label to be printed to. Default value is 17.4. Note: To print on a 150x100 label this value must be set to ‘15.0’	No
paper_dimensions.height_cm	number	Height of the label to be printed to. Default value is 10	No
paper_dimensions.stationery_size	string	Paper size upon which to print the label. Must be A4 or A5.	No
sender_details	object	An object containing the sender contact details. See Sender Details Object Parameters below.	Yes
sender_details.name	string(40)	Name of the sender.	Yes
sender_details.phone	string(20)	Phone number of the sender. NO SPACES, DIGITS and '+' ONLY	Yes
sender_details.email	string(254)	Email address of the sender.	No but highly desirable
sender_details.fax	string(26)	Contact fax number of the sender	No
sender_details.signatory	string(40)	Name of the individual sending the parcel, this is used for customs purposes.	No
sender_details.company_name	string(40)	Company name of the sender.	No
sender_details.customs_code	string(15)	Customs code of the sender.	No
receiver_details	object	An object containing the receiver contact details. See Receiver Details Object Parameters below.	Yes
receiver_details.name	string(40)	Name of the receiver.	Yes
receiver_details.phone	string(20)	Contact phone number of the receiver. NO SPACES, DIGITS and '+' ONLY	No but highly desirable
receiver_details.email	string(254)	Email address of the receiver.	No but highly desirable
receiver_details.fax	string(26)	Fax number of the person to receiver.	No
receiver_details.vat_number	string(25)	The VAT or GST number of the receiver. The field should not be > 14 characters.	No
receiver_details.registration_number	string(30)	Registration number of the receiver required for Delivery Location Options.	No
pickup_address	object	An object containing the sender pickup address details. This is the origin country address. See Pickup Address parameters below:	Yes
pickup_address.company_name	string(40)	Company name of the pickup address	No but highly desirable
pickup_address.building_name	string(40)	Building name of the pickup address.	No
pickup_address.street_number	string(10)	Street number of the pickup address.	No but highly desirable
pickup_address.street	string(40)	Street name of the pickup address.	Yes
pickup_address.suburb	string(40)	Suburb of the pickup address	No but highly desirable
pickup_address.city	string(40)	City of the pickup address	Yes
pickup_address.state	string(35)	Regional, provincial or county name of the pickup address.	No
pickup_address.locality_code	string(9)	Country subdivision code identifier that the pickup address belongs to.	No
pickup_address.country_code	string(2)	Two character country code of the pickup address.	Yes
pickup_address.postcode	string(17)	Postal or zip code of the pickup address.	Yes
delivery_address	object	An object containing the receiver delivery address details. See Receiver Address Object Parameters section	Yes
delivery_address.location_type	string(3)	Type of the delivery requested for the item. Value must be from UPU code list 199.	No
delivery_address.building_name	string(40)	Building name of the delivery address.	No
delivery_address.company_name	string(40)	Name of company that the parcel is being delivered to.	No
delivery_address.street_number	string(10)	Street number of the delivery address.	No but highly desirable
delivery_address.street	string(40)	Street name of the delivery address.	Yes
delivery_address.suburb	string(40)	Suburb of the delivery address	No
delivery_address.city	string(40)	City of the delivery address	Yes
delivery_address.state	string(35)	State Name or Two-letter US state code of the delivery address, e.g. TX, CA.	Yes
delivery_address.locality_code	string(9)	Country subdivision code identifier that the delivery address belongs to.	No
delivery_address.country_code	string(2)	Two character country code of the delivery address.	Yes
delivery_address.postcode	string(17)	The US ZIP code of the destination, in five or five + four format, e.g. 10118, or 10118-0110.	Yes
delivery_address.instructions	string(255)	Delivery instructions for courier	No
parcel_details	object	An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section	Yes
parcel_details.service_code	string(15)	Code to represent a delivery service. This is the service code.	Yes
parcel_details.receiver_charging_arrangement	string	Duty and tax payment method as it applies to the item. Value must be DDP (Delivery Duty Paid) OR DDU (Delivery Duty Unpaid)	No
parcel_details.undeliverable_instructions	string	Instructions in case of non-delivery. Value must be NONE, RETURN or DESTROY.	Yes
parcel_details.insurance_required	boolean	Whether insurance is required for the parcel. Value must be either true or false. Use false if the service does not support insurance	Yes
parcel_details.nature_of_transaction_code	string(3)	Category of Goods that appears on the CN23 form. Value depends on the nature of items. Must be one of: 11=Sale of Goods; 21=Returned Goods; 31=Gift; 32=Commercial Sample; 91=Documents; 991=Other	Yes
parcel_details.postage_paid_amount	number	Monetary value of postage that sender has paid. Value must be greater than 0.	No
parcel_details.additional_fee_amount	number	Monetary value of other fees that sender has paid. E.g. additional insurance	No
parcel_details.currency	string(3)	Currency code for the parcel	Yes
parcel_details.dimensions	object	An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section.	Yes
parcel_details.dimensions.length_cm	number	Length of the parcel.	Yes
parcel_details.dimensions.width_cm	number	Width of the parcel.	Yes
parcel_details.dimensions.height_cm	number	Height of the parcel.	Yes
parcel_details.dimensions.weight_kg	number	Physical weight of the parcel in kilograms.	No but highly desirable
parcel_details.dangerous_goods	object	An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section. Please refer to Dangerous Goods section for more information.	No
parcel_details.dangerous_goods.items.hazard_class	string(4)	Classification of dangerous items in the parcel. If provided must be 9	No
parcel_details.dangerous_goods.items.un_number	string(4)	United Nations Dangerous Goods identification code for dangerous items in the parcel. If provided must be either 3481 or 3091	No
parcel_details.parcel_contents	array	An array containing content details of a parcel.	Yes
parcel_details.parcel_contents.content_number	integer	Number specifying an item in the parcel. Value must be an integer between 1 to 20 inclusive.	Yes
parcel_details.parcel_contents.description	string(35)	Description of the parcel contents.	Yes
parcel_details.parcel_contents.harmonised_system_tariff	string(18)	10-digit tariff code from The Harmonized Tariff Schedule of the United States (HTS) at https://hts.usitc.gov	Yes
parcel_details.parcel_contents.quantity	integer	Quantity of units in the parcel.	Yes
parcel_details.parcel_contents.weight_kg	number	Weight of each individual unit in the parcel(kgs).	Yes
parcel_details.parcel_contents.value	number	Dollar value of each individual unit in the parcel.	Yes
parcel_details.parcel_contents.country_code	string(2)	Country code of the location in which the content piece was produced or manufactured. Value must be 2 characters.	Yes

Dangerous Goods - Lithium Battery`

Below are the details and validations that are implemented when the customer is requesting labels for parcels containing devices that have lithium batteries either packed with, or contained within.

Hazard Identification Details

Field	Description	Supported values
parcel_details.dangerous_goods.items.hazard_class	Classification of dangerous items-Lithium Battery in the parcel. Value must be from Hazard Identification Code.	9
parcel_details.dangerous_goods.items.un_number	Dangerous Goods-Lithium Battery identification code for dangerous goods in the parcel. Value must be 4 digits.	3091,3481

Supported services and details

Supported Label Provider (For Internal Use)	Supported service Codes	Remarks
GO_US_PROCESS (CS_US)	ICOUSUS	Destination US is available for the service.

Validations

Dangerous_Goods-Lithium Battery(LB) Validations	Validation results
Dangerous_Goods(DG) not provided in label request, then continue 'regular' label generation.	Label Generated.
Dangerous_Goods(DG) provided, but Label service is not Lithium Battery supported service label provider, then continue 'regular' label generation.	Label Generated.
Dangerous_Goods(DG) provided and Lithium Battery supported label provider, but service code is not Lithium Battery supported, then return an error message.	Error message: "The service is not available to send equipment including lithium batteries, visit nzpost.co.nz and search ECLB for more information."
Dangerous_Goods(DG) provided and service code is Lithium Battery supported service, but destination is not Lithium Battery supported destination, then return an error message.	Error message: "The last-mile delivery agent at the destination is not authorised to accept equipment including lithium batteries (ECLB), visit nzpost.co.nz and search ECLB for more information."
Dangerous_Goods(DG) provided and Lithium Battery supported service code and destination, but dangerous_goods/items/hazard_class is NOT 9, then return an error message.	Error message: "The only acceptable value of the field hazard_class is “9”, representing Class 9 - miscellaneous dangerous goods, which the lithium batteries are classified as."
Dangerous_Goods(DG) provided, Lithium Battery supported service code and destination, but dangerous_goods/items/un_number is NOT 3091 or 3481, then return an error message.	Error message: "The acceptable value of the field un_number is “3481” - Lithium ion batteries contained in equipment or “3091”- Lithium ion batteries packed with equipment."
Dangerous_Goods(DG) provided, Lithium Battery supported service code and destination, dangerous_goods/items/hazard_class is 9 and dangerous_goods/items/un_number is in (3091 or 3481), then continue label generation with ECLB indicator.	Label Generated with ECLB indicator.

Intl Courier Select United States

This example shows sending from NZ origin to US.

Update all fields in the request to match your own.

{
    "sender_details": {
        "name": "Sender Company Name",
        "phone": "+64123456789",
        "email": "sendercompany@nzpost.co.nz",
        "company_name": "Test Sender Company",
        "signatory": "Sender Company Limited"
    },
    "pickup_address": {
        "city": "Auckland",
        "company_name": "Stark Industries",
        "country_code": "NZ",
        "postcode": "1025",
        "street": "4A Stewart Road, Mt Albert",
        "suburb": "Auckland"
    },
    "receiver_details": {
        "name": "Test Receiver",
        "phone": "6490000002",
        "email": "testreceiver@nzpost.co.nz"
    },
    "delivery_address": {
        "instructions": "Leave at back door",
        "city": "Houston",
        "state": "TX",
        "country_code": "US",
        "postcode": "77072",
        "street": "11319 Sharpcrest St"
    },
    "parcel_details": [
        {
            "service_code": "ICOUSUS",
            "undeliverable_instructions": "RETURN",
            "insurance_required": false,
            "nature_of_transaction_code": "11",
            "postage_paid_amount": 0.01,
            "currency": "NZD",
            "dangerous_goods": {
                "items": [
                    {
                        "un_number": "3091",
                        "hazard_class": "9"
                    }
                ]
            },
            "dimensions": {
                "length_cm": 16.0,
                "width_cm": 15.0,
                "height_cm": 10.0,
                "weight_kg": 0.300
            },
            "parcel_contents": [
                {
                    "content_number": 1,
                    "description": "Vitamin C tablet",
                    "harmonised_system_tariff": "2936.27.0000",
                    "quantity": 1,
                    "weight_kg": 0.3,
                    "value": 150.81,
                    "country_code": "NZ"
                }
            ]
        }
    ]
}

Response Parameters

Field Name	Description	Mandatory
consignment_id	Unique identifier for the consignment if the request is successful.	Yes
message_id	A unique ID for the API call	Yes
success	Returns true if request is successful. Returns false if request is not successful.	Yes

Duties and Taxes

You, as the sender, are liable for the destination duties, taxes and other regulatory charges which are charged by the U.S. Customs Border Protection and other border agencies. An estimate is calculated and displayed during label generation based on the information you have provided to help you understand these costs, and will be made available to you through our API. NZ Post does not guarantee any estimate provided for duties and taxes.

The information is in the 'shipment_summary' object of the /status call.

"shipment_summary": {
        "total_duties": 51.42,
        "total_taxes": 0,
        "total_fees": 16.66,
        "currency": "NZD"
    }

In rare cases, there may be a failure to calculate duties and taxes. You will still be able to generate a label to send your item, however we will be unable to provide estimated duties and taxes to you through our API. You, as the sender, are responsible for understanding what duties and taxes will be due on your goods.

The following error message will be returned if the duties and taxes is failed to be calculated.

"shipment_summary": {
        "error": "The shipment summary was not able to be calculated, but you can still send the item."
    }

Sample Response - /labels endpoint

{
    "success": true,
    "message_id": "2ec485a0-7ca1-11f0-b661-0232d3c3ab47",
    "consignment_id": "AGMJHQ"
}

Sample Response - /labels/status endpoint

{
    "consignment_id": "AGMJHQ",
    "consignment_status": "Complete",
    "consignment_url": "https://api.nzpost.co.nz/parcellabel/v3/labels/AGMJHQ?format=PDF",
    "errors": [],
    "expiry_date_utc": "2025-10-24T01:24:29.168",
    "labels": [
        {
            "errors": [],
            "label_generation_status": "Complete",
            "label_id": "AGMJHQ-1",
            "tracking_reference": "9261290378006801003185"
        }
    ],
    "message_id": "4b367670-8152-11f0-b661-0232d3c3ab47",
    "page_urls": [
        "https://api.nzpost.co.nz/parcellabel/v3/labels/AGMJHQ?format=PNG&page=1"
    ],
    "dangerous_goods_declaration_urls": [
        "https://api.nzpost.co.nz/parcellabel/v3/labels/AGMJHQ/DG/1"
    ],
    "shipment_summary": {
        "total_duties": 51.42,
        "total_taxes": 0,
        "total_fees": 16.66,
        "currency": "NZD"
    },
    "success": true
}

Error Handling

Error messages will be returned if the label cannot be generated.
Most of these are generated by our system, but some are generated by our third-party provider and we return these as-is.
Error messages will describe the steps you can take to fix the label request to have it successful.

If you cannot determine how to fix the label request, please contact our support at api@nzpost.co.nz.
The following are some examples of error messages that can be returned.

must have delivery_address.state	"code": 400001, "details": "delivery_address.state must be a valid US state. E.g. CA, TX.", "message": "Validation error occurred while processing request."
must have delivery_address.postcode or invalid postcode	"code": 400002, "details": "Parcel 1 has failed eligibility checking. You must provide a valid US zip in the destination postcode field. Please enter 5 digits (12345) or 9 digits with hyphen (12345-6789).", "message": "Invalid parameter(s)"
parcel_details.currency must be valid	"code": 400001, "details": "Could not convert currency US. Please check parcel details currency field has correct currency value", "message": "Bad Request"
must include parcel_contents.country_code	"code": 400001, "details": "parcel_details[0].parcel_contents[0].country_code is empty or null", "message": "Bad request"
invalid tariff	"code": 400001, "details": "The provided HS code for description: honey is not valid. Please provide valid HS code of the item(s)", "message": "Bad request"
must be US country code	"code": 400002, "details": "Parcel 1 has failed eligibility checking. The service does not support the destination country AU", "message": "Invalid parameter(s)"
multi parcel	"code": 400001, "details": "Unfortunately GOUSProcess services do not support multi-parcel label generation currently. Please refer to documentation or contact techsupport@nzpost.co.nz for more information.", "message": "Bad request"
max value $1000NZD	"code": 400002, "details": "Parcel 1 has failed eligibility checking. The service ICOUSUS does not support items over $1000. Your item was $1000.01", "message": "Invalid parameter(s)"
max weight 22kg	"code": 400002, "details": "Parcel 1 has failed eligibility checking. Your items weight is larger than the maximum weight supported by this product. Your item weight is 22.01 kg and the service maximum is 22 kg", "message": "Invalid parameter(s)"
max dimension 1.5m	"code": 400002, "details": "Parcel 1 has failed eligibility checking. Your items maximum dimension is larger than the maximum dimension supported by this product. Your item maximum dimension is 150.01 cm and the service maximum is 150 cm", "message": "Invalid parameter(s)"
max girth 3m	"code": 400002, "details": "Parcel 1 has failed eligibility checking. Your items girth is larger than the maximum supported by this product. Your item is 400.02 cm and the maximum is 300 cm. Try to use a compatible service, or contact techsupport@nzpost.co.nz if you require further ", "message": "Invalid parameter(s)"